Documentation and Tutorial
by Erik Roberts

Table of contents

GIMBL-Vis (GV):
an interactive multi-dimensional visualization toolbox for Matlab

Installation

  • Download the zip file or clone the git repository for GIMBL-Vis
  • Do the same for the MultiDimensional Dictionary (MDD) class.
  • Add the GIMBL-Vis and MDD folders to your matlab path
    • If you don't already have one, create a file named startup.m in the following folder:
    • If using Mac/Linux, use this folder: "/Documents/MATLAB"
    • If using Windows, use this folder: ""
    • Put the following line in the "startup.m" file: "addpath(genpath(fullfile('your', 'custom', 'path', 'to', 'GIMBL-Vis')))" (if your path to GIMBL-Vis is "your/custom/path/to/GIMBL-Vis").

Getting Started

  • Open GV by evaluating gv like a function: myGVsession = gv.Run();
    • gv is a class containing data and methods to operate on that data
    • The above command will create an object, i.e. instance, of the gv class
    • Creating an object of the gv class and calling the Run method is like opening an application on your computer, e.g. Matlab, since it will open a new GV GUI window
  • A new GV GUI window is opened
  • There are 2 ways to interact with GV (i.e., to modify the gv object state)
    1. Using the Matlab command window
    2. Using the GUI window.
      • Each gv object that is called will open a new GV GUI window with its own data store.

Data Types and Sources

Data types:

  • Matlab numeric array
  • Matlab cell array (which can contain any data or be empty)
  • Spreadsheet text
  • Dynasim data

Data sources:

  • Matlab workspace
  • Saved mat files
  • Saved spreadsheets (e.g., csv, tsv, txt, xls, xlsx)
  • Dynasim directory containing a studyinfo.mat file

Hypercube

"A hypercube is an n-dimensional analogue of a square (n = 2) and a cube (n = 3)"

GV Hypercube

  • GV permits the loading, importing, and merging of different datasets into the same GV session
  • Each separate set of axes is called a hypercube in GV
  • One can merge new data into a given hypercube

DynaSim Integration

  • GV was created with DynaSim integration as a core feature
  • 2 ways to import DynaSim data:
  • Navigate to Dynasim output directory and call gv.Run, or call gv.Run(output_dir_path).
  • Use the GV gui, click on "File > Import Multidimensional Data", and select the studyinfo.mat file

Implementation Details

  • Internally, gv objects store each hypercube dataset inside a field of the mdData structure property (i.e. object variable).
  • The field name corresponds to the hypercube name.
  • Each hypercube dataset is stored in a gvArray, which is a subclass of the MultiDimensional Dictionary (MDD) class.
  • The default MDDAxis objects inside of MDD are replaced with a gvArrayAxis subclass for gvArrays.
  • See DEV-README.md for more details